<script type="text/html" data-help-name="e-mail">
    <p>Sends the <code>msg.payload</code> as an email, with a subject of <code>msg.topic</code>.</p>
    <p>The default message recipient can be configured in the node, if it is left
    blank it should be set using the <code>msg.to</code> property of the incoming message. If left blank
    you can also specify any or all of: <code>msg.cc</code>, <code>msg.bcc</code>, <code>msg.replyTo</code>,
    <code>msg.inReplyTo</code>, <code>msg.references</code>, <code>msg.headers</code>, or <code>msg.priority</code> properties.</p>
    <p>You may optionally set <code>msg.from</code> in the payload which will override the <code>userid</code>
    default value.</p>
    <h3>Gmail users</h3>
    <p>If you are accessing Gmail you may need to either enable <a target="_new" href="https://support.google.com/mail/answer/185833?hl=en">an application password</a>.</p>
    <h3>Authentication</h3>
    <p>When connecting to a SMTP server, two authentication types are available: Basic and XOAuth2.</p>
    <ul>
        <li><b>Basic:</b> requires a username and password to be entered</li>
        <li><b>XOAuth2:</b> requires a username and a <code>msg</code> property to extract the access token</li>
    </ul>
    <h3>SASL Formatting:</h3>
    <p>SASL XOAuth2 tokens are created by combining the username and token, encoding it in base64, and passing it to the mail server in the following format:</p>
    <pre>base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A")</pre>
    <p>If the checkbox is unticked, flow creators can format the token themselves before passing it to the node.</p>
    <h3>Details</h3>
    <p>The payload can be html format. You may supply a separate plaintext version using <code>msg.plaintext</code>.
    If you don't and <code>msg.payload</code> contains html, it will also be used for the plaintext.
    <code>msg.plaintext</code> will be ignored if <code>msg.payload</code> doesn't contain html.</p>
    <p>If the payload is a binary buffer then it will be converted to an attachment.
    The filename should be set using <code>msg.filename</code>. Optionally <code>msg.description</code> can be added for the body text.</p>
    <p>Alternatively you may provide <code>msg.attachments</code> which should contain an array of one or
    more attachments in <a href="https://nodemailer.com/message/attachments/" target="_new">nodemailer</a> format.</p>
    <p>If required by your recipient you may also pass in a <code>msg.envelope</code> object, typically containing extra from and to properties.</p>
    <p>If you have own signed certificates, Nodemailer can complain about that and refuse sending the message. In this case you can try switching off TLS.</p>
    <p><b>Note</b>: uses SMTP with SSL to port 465.</p>
    <h3>Use secure connection</h3>
    <p>If enabled the connection will use TLS when connecting to server. If disabled then TLS is used if server supports the STARTTLS extension. In most cases set this to enabled if you are connecting to port 465. For port 587 or 25 keep it disabled.</p>

</script>

<script type="text/html" data-help-name="e-mail in">
    <h3>Overview</h3>
    <p>The e-mail in node retrieves emails from a POP3 or IMAP server and forwards the email data as a message if it has not already been seen.</p>
    
    <h3>Message Properties</h3>
    <p>The following properties are set on the message object:</p>
    <ul>
        <li><code>msg.topic</code> - the subject of the email</li>
        <li><code>msg.payload</code> - the plain text body of the email</li>
        <li><code>msg.html</code> - the HTML body of the email (if present)</li>
        <li><code>msg.from</code> - the sender of the email</li>
        <li><code>msg.date</code> - the date the email was sent</li>
        <li><code>msg.header</code> - the complete header object including information such as the "to" and "cc" recipients</li>
        <li><code>msg.attachments</code> - an array of objects representing any attachments included in the email</li>
    </ul>
    
    <h3>Module Used</h3>
    <p>The e-mail in node uses the <a href="https://github.com/mscdex/node-imap/blob/master/README.md" target="_new">node-imap module</a>, see that page for information on the <code>msg.criteria</code> format if needed.</p>
    <p>It also makes use of <a href="https://github.com/node-pop3/node-pop3#readme" target="_new">node-pop3 module</a></p>
    
    <h3>Attachment Format</h3>
    <p>Each object in the <code>msg.attachments</code> array is formatted as follows:</p>
    <pre>
    {
        contentType:        // The MIME content description
        fileName:           // A suggested file name associated with this attachment
        transferEncoding:   // How was the original email attachment encoded?
        contentDisposition: // Unknown
        generatedFileName:  // A suggested file name associated with this attachment
        contentId:          // A unique generated ID for this attachment
        checksum:           // A checksum against the data
        length:             // Size of data in bytes
        content:            // The actual content of the data contained in a Node.js Buffer object
                            // We can turn this into a base64 data string with content.toString('base64')
    }
    </pre>
    <h3>Authentication</h3>
    <p>When connecting to a POP3 or IMAP server, two authentication types are available: Basic and XOAuth2.</p>
    <ul>
        <li><b>Basic:</b> requires a username and password to be entered</li>
        <li><b>XOAuth2:</b> requires a username and a <code>msg</code> property to extract the access token</li>
    </ul>
    <p>With XOAuth2 authentication, periodic fetching is not available. The node will only attemp to login when a new token is receieved.</p>
    <h3>SASL Formatting:</h3>
    <p>SASL XOAuth2 tokens are created by combining the username and token, encoding it in base64, and passing it to the mail server in the following format:</p>
    <pre>base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A")</pre>
    <p>If the checkbox is unticked, flow creators can format the token themselves before passing it to the node.</p>

    <h3>Notes</h3>
    <ul>
        <li>For POP3, the default port numbers are 110 for plain TCP and 995 for SSL.  For IMAP the port numbers are 143 for plain TCP and 993 for SSL.</li>
        <li>With option 'STARTTLS' an established plain connection is upgraded to an encrypted one. Set to 'always' to always attempt connection upgrades via STARTTLS, 'required' only if upgrading is required, or 'never' to never attempt upgrading.</li>
        <li>The maximum refresh interval is 2147483 seconds (24.8 days).</li>
    </ul>

</script>

<script type="text/html" data-help-name="e-mail mta">
    <p>Mail Transfer Agent - listens on a port for incoming SMTP mails.</p>
    <p><b>Note</b>: Default configuration is "NOT for production use" as security is not enabled.
    This is primarily for local testing of outbound mail sending, but could be used
    as a mail forwarder to a real email service if required.</p>
    <p>To use ports below 1024, for example 25 or 465, you may need to get privileged access.
    On linux systems this can be done by running
    <pre>sudo setcap 'cap_net_bind_service=+eip' $(which node)</pre>
    and restarting Node-RED. Be aware - this gives all node applications access to all ports.</p>
    <h3>Security</h3>
    <p>When <i>Secure connection</i> is checked, the connection will use TLS.
    If not it is still possible to upgrade clear text socket to TLS socket by checking <i>Start TLS</i>.
    In most cases when using port 465, check <i>Secure connection</i>. For port 587 or 25 keep it disabled, use <i>Start TLS</i> instead.</p>
    <p>If you do no specify your own certificate (path to file) then a pregenerated self-signed certificate is used. Any respectful client refuses to accept such certificate.</p>
    <h3>Authentication</h3>
    <p>Authentication can be enabled (PLAIN or LOGIN). Add at least one user.</p>
    <h3>Expert</h3>
    <p>All options as described in <a href="https://nodemailer.com/extras/smtp-server/" target="_new">nodemailer SMTP server</a> can be made here.</p>
</script>
